improvement(workflows): centralize v2 application operations - #6411

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
docs	Skipped		Aug 8, 2026 5:41pm

PR Summary

Medium Risk
Broad refactor of v2 auth, execution, and lifecycle APIs with behavior-preserving contracts but new admission and authorization paths; regression risk is mitigated by extensive tests but execution and billing-adjacent flows warrant careful review.

Overview
Centralizes the public v2 workflow surface on defineV2JsonRoute plus shared Principal-aware application use cases (readWorkflow, deployWorkflow, executeWorkflowOperation, run list/read/cancel/resume, folders, import/export, versions). Route files mostly map contract inputs, present responses, and hook analytics; authorization, orchestration, and workspace policy live in the application layer with v2WorkflowErrorPolicies (workflow/run auth failures masked as 404 where appropriate).

Execute switches from v1-style auth to admitV2Request / authenticateV2ApiKey for keyed callers, routes them through executeWorkflowOperation, and applies request-rate buckets before execution preprocessing (sync/async quota, billing, concurrency). Anonymous public API execution still uses the legacy executeWorkflowService path when no API key is present.

Deploy / rollback / undeploy responses now surface activeDeployment and latestDeploymentAttempt from use-case results instead of only a boolean deployed flag.

Resume is split: resume-handler adapts executeResumeWorkflow results to legacy/v2 HTTP shapes; the v2 resume route uses resumeWorkflowRun with admission-first ordering and structured v2 run receipts.

Removes resolveV2WorkflowAccess (app/api/v2/workflows/lib/access.ts) in favor of the shared route framework and application authorization.

^{Reviewed by Cursor Bugbot for commit a5a2bd1. Bugbot is set up for automated code reviews on this repo. Configure here.}

Greptile Summary

The PR centralizes v2 workflow operations behind Principal-aware application use cases while preserving transport-specific responses and analytics.

• Moves workflow CRUD, folder, deployment, version, import/export, run, cancellation, resume, and keyed-execution behavior into shared application operations.
• Introduces canonical workspace authorization and principal attribution for personal, workspace, session, and delegated identities.
• Shares deployment and resume lifecycle behavior between v2 and internal adapters while retaining their polling and response contracts.

Confidence Score: 5/5

The PR appears safe to merge because no blocking failure remains within the eligible follow-up-review scope.

No blocking failure remains.

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  Client[API client or internal caller] --> Adapter[Route adapter]
  Adapter --> Auth[Principal authentication and rate admission]
  Auth --> UseCase[Authorized workflow use case]
  UseCase --> Context[Canonical workflow and workspace context]
  Context --> Authorization[Workspace authorization]
  Authorization --> Operation[Workflow operation]
  Operation --> Lifecycle[CRUD, deployment, execution, runs, or resume]
  Lifecycle --> Presenter[Surface-specific response, analytics, and audit]
  Presenter --> Client

_{Reviews (2): Last reviewed commit: "fix(workflows): avoid locking folder tre..." | Re-trigger Greptile}

@greptile

@cursor review